Conversation
|
|
||
| ## Steps | ||
|
|
||
| ### 1. Setup Task Environment |
There was a problem hiding this comment.
Out of curiosity, is this section the same content as the other ones?
| #### 3.2 Identify Document Type | ||
|
|
||
| **Constraints:** | ||
| - You MUST identify the document type: |
There was a problem hiding this comment.
We don't really have any of these, do we? Concept/QuickStart/Example is mostly what we have?
| - Start with the simplest possible example | ||
| - Add complexity progressively if needed | ||
| - Use clear, descriptive variable names | ||
| - You MUST test every code example by executing it |
There was a problem hiding this comment.
How well has this worked for you? For release note validation, I struggled with getting the agent to test it comprehensively (e.g. not just assert True == something.var)
There was a problem hiding this comment.
Feature 6 here is a perfect example FWIW: zastrowm/sdk-python#27 (comment); gotta love that assert hook is not None!
| - Execute TypeScript examples to verify they work (if applicable) | ||
| - Fix any errors before including in documentation | ||
| - You MUST validate examples against the PR — ensure they use the new feature correctly and reflect the actual API | ||
| - You MUST record which examples passed/failed in your notebook |
There was a problem hiding this comment.
We should ensure that it's reported in the PR - just recording doesn't help much IMHO
| - Have I helped them build a mental model of how it works? | ||
| - Have I told them when to use this vs. alternatives? | ||
| - You MUST follow the document type template from the style guide | ||
| - You MUST use the correct MkDocs formatting (admonitions, tabs, etc.) |
There was a problem hiding this comment.
Trying to make my "CMS-migration" job harder I see ;)
|
|
||
| ### Writing Style | ||
|
|
||
| - Limit sentences to 25 words or fewer |
There was a problem hiding this comment.
Anything about using paragraphs more than lists? ;)
|
|
||
| ### Formatting | ||
|
|
||
| #### Headings |
There was a problem hiding this comment.
Do we have guidelines about bolding? That's another one I often comment on.
LLMs seem to want to:
- Use lists: To format data
- Use bolding: To separate the summary before explaining
- Over use the pattern: Throughout the doc
Between the headings and bolding, I feel like it's too much - though IIRC you & I have disagreed on that in the past
| ### Punctuation and Style | ||
|
|
||
| - Oxford comma: Always | ||
| - Semicolons: Don't use |
|
|
||
| Use descriptive link text, never "click here" or bare URLs. | ||
|
|
||
| ### Punctuation and Style |
There was a problem hiding this comment.
What about dashes?
I'd suggest "use sparingly"? I see in a lot of comment threads about AI folks repeating "this is obviously AI" because of the dashes.
|
|
||
| Before committing, verify: | ||
|
|
||
| ### Voice and Tone |
2 participants
Issue #, if available:
Description of changes:
Adding a doc writer SOP to use
/strands docs. This will allow us to auto-generate docs.The SOP is generated based on our documentation so far. It's based on the guidelines I have been using for a month now
By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.